-------------------------------------------------------------------------------
Apple ][ Tools
Copyright (c) 2008 Sebastian Kienzl <seb at riot dot org>
2008-09-15
-------------------------------------------------------------------------------

Hello!

Here are two small tools connected to the cassette port of the Apple ][.
With "a2audioup" you can load binary data into the Apple's RAM and
"a2cassdecode" decodes audio coming from the cassette-port to binary.

I wrote these tools mainly to archive my old disks. I couldn't use ADTPro
because my Apple only no memory extension and thus no ProDOS.

Except that you need these tools to backup DOS-disks (see my webpage), they
are also useful stand-alone. With "a2audioup" you basically get a simple
Dev-Environment, since you can put data from the PC into the Apple's RAM.

a2audioup
~~~~~~~~~
	This application:
	
	* loads a binary file
	* "modulates" the data to audio-data that can be loaded via the
	  Apple ]['s cassette port
	* saves it as a WAV file
	OR
	* plays that audio-data (Windows only)

	Using it
	~~~~~~~~
	
	Obviously your soundcards line-out must be connected to the Apple ]['s
	"CASSETTE IN", because you're sending data FROM the PC TO the Apple.
	
	Call the binary without any parameters to see all the possible parameters.
	On Linux (or any POSIX-platform), you'll have to save the binary to a WAV
	and play it somehow, on Windows the app will play it directly if no
	output-file is given. If you're under Windows and have more then one
	soundcard available, you may be happy about the -l and -d parameters.
	
	Type "CALL -151" on the Apple, that will start the so called "ROM Monitor",
	a description of all the commands can be found in the
	"APPLE ][ REFERENCE MANUAL" or other books.
	
	Launch a "tape read"-command, for example:
	
	*2000.20FFR
	
	This will put 256 (NOT 255, as one may think, the end-address is included)
	bytes coming from CASSETTE IN to the addresses 0x2000 to 0x20ff.
	
	After you pressed enter, the Apple will wait for data. Now play the written
	WAV-file or make a2audioup play the audio (under Windows). Note that the
	size of the sent data and the resulting size of the read-command have to
	be the same, otherwise the upload will fail -- this is due to a "checksum"
	that's transmitted at the end of a block.
	
	If you uploaded some opcodes, you can start your program by for example:
	
	*2000G

	This will issue a "JSR $2000".

	That's what I used when I wrote the diskdumper, maybe that snippet is
	of use to you:
	
	---------8x-----------------------
	@echo off
	dasm test.asm -f3 -otest.bin
	bash -c "let to=3072+$(stat -c%%s test.bin)-1; printf 'c00.%%xr\n' $to"
	pause
	a2audioup -i test.bin -d 1
	---------8x-----------------------
	
	Except that it assembles a file, it also displays the ROM-monitor-command
	I need to type at the Apple. The program was loaded to 0xc00 (3072).
		

a2cassdecode
~~~~~~~~~~~~
	This application takes audio recorded from the
	Apple ]['s CASSETTE OUT-port, decodes it and saves the result.
	
	The input-file must be unsigned 8-bit/mono audio, for example a WAV. Since
	the header isn't evaluated, you could also give a RAW file. I have only
	tried files recorded at 44100Hz, but the code should calibrate itself on
	lower frequencies too.
	
	In the simplest case you use some Wave-recorder (Audacity, Wavelab, etc.),
	record at 44100Hz/mono/8-bit and save the result to a WAV-file.
	
	Then you pass the file to a2cassdecode and voilá! Note that there can
	be multiple blocks of data in the audio - they will just be saved one after
	another.
	
	The output will look like this:
	
	---------8x-----------------------
	DC=-9.00
	
	33.32 secs      : sync found, period is 28, samplefreq is ~43076.92
	43.86 secs      : data starts
	165.25 secs     : data ends: 29952 bytes, checksum OK
	
	187.97 secs     : sync found, period is 28, samplefreq is ~43076.92
	198.51 secs     : data starts
	319.90 secs     : data ends: 29952 bytes, checksum OK
	
	345.09 secs     : sync found, period is 28, samplefreq is ~43076.92
	355.62 secs     : data starts
	480.88 secs     : data ends: 29952 bytes, checksum OK
	
	505.92 secs     : sync found, period is 28, samplefreq is ~43076.92
	516.46 secs     : data starts
	642.38 secs     : data ends: 29952 bytes, checksum OK
	
	666.18 secs     : sync found, period is 28, samplefreq is ~43076.92
	676.72 secs     : data starts
	775.20 secs     : data ends: 23552 bytes, checksum OK
	
	Total: 143360 bytes	
	---------8x-----------------------
	
	I've never had any problems with decoding-errors, if you have them, try
	increasing the SNR.
	
That's all, if you have any questions: too bad! :)
